🕸️ Ada Research Browser

CONTRIBUTING.md
Home›Research Reports›CONTRIBUTING.md
← Back

Contributing to CMMC Watch

Thank you for considering contributing to CMMC Watch! This document provides guidelines and instructions for contributing.

🎯 Ways to Contribute

🚀 Getting Started

1. Fork and Clone

# Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/cmmcwatch.git
cd cmmcwatch

# Add upstream remote
git remote add upstream https://github.com/fubak/cmmcwatch.git

2. Set Up Environment

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Add your API keys to .env
# See README.md for instructions on getting free API keys

3. Create a Branch

# Create a branch for your changes
git checkout -b feature/your-feature-name

# Or for bug fixes:
git checkout -b fix/bug-description

💻 Development Workflow

Running the Pipeline

# Full pipeline run
cd scripts
python main.py

# Skip archiving (faster for testing)
python main.py --no-archive

# Dry run (collect data only, don't build)
python main.py --dry-run

Testing Individual Components

# Test trend collection
python scripts/collect_trends.py

# Test image fetching
python scripts/fetch_images.py

# Test design generation
python scripts/generate_design.py --test

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=scripts --cov-report=html

# Run only fast tests (skip slow integration tests)
pytest -m "not slow"

# Run specific test file
pytest tests/test_config.py -v

Code Quality

# Format code with ruff
ruff format scripts/

# Lint code
ruff check scripts/

# Fix auto-fixable issues
ruff check scripts/ --fix

# Type checking (optional, mypy is configured loosely)
mypy scripts/

📝 Code Style Guidelines

Python Style

Example Function

def fetch_data(url: str, timeout: int = 15) -> dict:
    """
    Fetch data from a URL with retry logic.

    Args:
        url: The URL to fetch from
        timeout: Request timeout in seconds

    Returns:
        Parsed JSON response as a dictionary

    Raises:
        requests.RequestException: If request fails after retries
    """
    # Implementation here
    pass

Naming Conventions

🧪 Testing Guidelines

Writing Tests

Test Categories

Example Test

def test_categorize_trend():
    """Test trend categorization logic."""
    collector = TrendCollector()

    category = collector._categorize_trend(
        "CMMC 2.0 certification requirements",
        "New CMMC certification process announced"
    )

    assert category == "cmmc_program"

📦 Adding Data Sources

Adding an RSS Feed

  1. Edit scripts/config.py
  2. Add to CMMC_RSS_FEEDS dictionary:
CMMC_RSS_FEEDS = {
    # ... existing feeds
    "New Source Name": "https://example.com/feed.xml",
}
  1. Test the feed:
python scripts/collect_trends.py
  1. Submit PR with description of the source and why it's relevant

Adding Keywords

Edit the relevant keyword list in scripts/config.py:

CMMC_CORE_KEYWORDS = [
    # ... existing keywords
    "new-keyword",
]

🔄 Pull Request Process

Before Submitting

  1. Update from upstream: bash git fetch upstream git rebase upstream/main

  2. Run tests: bash pytest

  3. Format code: bash ruff format scripts/ ruff check scripts/ --fix

  4. Update documentation if needed

Submitting the PR

  1. Push your branch: bash git push origin feature/your-feature-name

  2. Go to GitHub and create a Pull Request

  3. Fill out the PR template:

  4. Title: Clear, descriptive title
  5. Description: What does this PR do? Why?
  6. Testing: How did you test this?
  7. Screenshots: If UI changes

PR Review Process

🐛 Bug Fix Guidelines

Before Fixing a Bug

  1. Check existing issues - Has this been reported?
  2. Reproduce the bug - Can you consistently trigger it?
  3. Create an issue if one doesn't exist

Writing a Bug Fix

  1. Add a test that reproduces the bug
  2. Fix the bug
  3. Verify the test now passes
  4. Submit PR referencing the issue number

🎨 UI/Design Changes

Guidelines

Testing UI Changes

# Build the website
python scripts/main.py

# Open public/index.html in a browser
# Test on different screen sizes

📖 Documentation Changes

Types of Documentation

Documentation Style

⚡ Performance Considerations

Guidelines

Cost Optimization

🔒 Security Guidelines

Do Not

Do

📞 Getting Help

📜 License

By contributing, you agree that your contributions will be licensed under the MIT License.

🙏 Thank You!

Your contributions make CMMC Watch better for everyone in the compliance community!

Happy Contributing! 🎉